<html>
<head><meta charset="utf-8"><title>Documenting ptr::raw_const · t-lang/wg-unsafe-code-guidelines · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/index.html">t-lang/wg-unsafe-code-guidelines</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html">Documenting ptr::raw_const</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="220874335"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220874335" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220874335">(Dec 24 2020 at 15:00)</a>:</h4>
<p><span class="user-mention" data-user-id="120791">@RalfJ</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Creating.20a.20safe.20interface.20to.20Thin.20Trait.20Objects/near/220525672">said</a>:</p>
<blockquote>
<blockquote>
<p>What does that mean for code where you go from a pointer to an object to a pointer to one of its fields?</p>
</blockquote>
<p>It means you should be using <code>ptr::raw_const!/raw_mut!</code>. Which unfortunately isn't stable yet... <a href="https://github.com/rust-lang/rust/issues/73394">FCP is done</a>, but rustdoc <a href="https://github.com/rust-lang/rust/issues/74355">has a bug</a> that makes it currently infeasible to stabilize the macro... :/<br>
(Out of all the barriers this macro had to overcome -- it's been a long time in the making -- this is the one that I least expected.^^ And the most frustrating thing is that fixing it is waay outside my area of expertise.)</p>
</blockquote>
<p>I'm sure you've tried this already, but in case not - is there a reason it needs to specifically be a declarative macro? I think you can re-export the macro in <code>std::ptr</code>, and then use <code>doc(hidden)</code> on the one in the root if you don't want people using it. <a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2018&amp;gist=51eed0e06f153d96136e5dcce6ff95a4">https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2018&amp;gist=51eed0e06f153d96136e5dcce6ff95a4</a></p>



<a name="220874771"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220874771" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220874771">(Dec 24 2020 at 15:09)</a>:</h4>
<p>hmm let me try that in more detail, one sec</p>



<a name="220874953"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220874953" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220874953">(Dec 24 2020 at 15:13)</a>:</h4>
<p>ok it does work but not if you add <code>doc(hidden)</code>, I guess that carries over to the re-export</p>



<a name="220875024"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220875024" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220875024">(Dec 24 2020 at 15:14)</a>:</h4>
<p><span class="user-mention" data-user-id="120791">@RalfJ</span> would you be ok with documenting <code>std::raw_const!</code> in the root? If not I can ask about making doc(hidden) only apply to the original definition, that wouldn't be hard to implement, just a policy decision</p>



<a name="220875052"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220875052" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220875052">(Dec 24 2020 at 15:15)</a>:</h4>
<p>(specifically removing this line: <a href="https://github.com/rust-lang/rust/blob/2acf6ee6d2ab3acf3f4d2117591ac1143c8232fe/src/librustdoc/clean/mod.rs#L2170">https://github.com/rust-lang/rust/blob/2acf6ee6d2ab3acf3f4d2117591ac1143c8232fe/src/librustdoc/clean/mod.rs#L2170</a>)</p>



<a name="220877455"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220877455" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220877455">(Dec 24 2020 at 16:04)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Creating.20a.20safe.20interface.20to.20Thin.20Trait.20Objects/near/220875024">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="120791">RalfJ</span> would you be ok with documenting <code>std::raw_const!</code> in the root? If not I can ask about making doc(hidden) only apply to the original definition, that wouldn't be hard to implement, just a policy decision</p>
</blockquote>
<p>I thought of that a while ago; I think the best solution in that regard would be to add another <code>doc</code> attribute / or a special meaning to <code>#[doc(inline)]</code> so that we can have the capability to "unhide" stuff by inlining it: <em>e.g.</em>,<code>#[doc(inline_unhidden)]</code></p>



<a name="220877478"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220877478" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220877478">(Dec 24 2020 at 16:05)</a>:</h4>
<p>Also, now that it's finally holidays, I have time to catch up with my delayed doc PR and hopefully fix the link bug <span aria-label="fingers crossed" class="emoji emoji-1f91e" role="img" title="fingers crossed">:fingers_crossed:</span></p>



<a name="220879011"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220879011" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220879011">(Dec 24 2020 at 16:32)</a>:</h4>
<p><span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> I guess my question is when people want doc(hidden) to <em>also</em> apply to the re-export</p>



<a name="220879024"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220879024" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220879024">(Dec 24 2020 at 16:32)</a>:</h4>
<p>that seems needlessly limiting when you can always add <code>#[doc(hidden)] pub use x::y;</code></p>



<a name="220879037"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220879037" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220879037">(Dec 24 2020 at 16:33)</a>:</h4>
<p>adding more attributes seems like technical debt</p>



<a name="220881662"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220881662" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220881662">(Dec 24 2020 at 17:25)</a>:</h4>
<p>I don't care about the default, I just think that <code>#[doc(no_inline)]</code> should not "unhide it", and I was just being careful with not breaking some form of "expected behavior" of <code>#[doc(hidden)]</code>. I do agree that if the <code>pub use</code> needs to be hidden, it can be so annotated too <span aria-label="smile" class="emoji emoji-1f642" role="img" title="smile">:smile:</span></p>



<a name="220884717"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220884717" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220884717">(Dec 24 2020 at 18:35)</a>:</h4>
<p>if the only concern is backwards-compatibility, we could make it opt-in with a feature gate or something</p>



<a name="220884739"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220884739" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220884739">(Dec 24 2020 at 18:35)</a>:</h4>
<p>(could someone move this to <a class="stream" data-stream-id="266220" href="/#narrow/stream/266220-rustdoc">#rustdoc</a> ?)</p>



<a name="220925154"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220925154" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> RalfJ <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220925154">(Dec 25 2020 at 15:17)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220875024">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="120791">RalfJ</span> would you be ok with documenting <code>std::raw_const!</code> in the root? If not I can ask about making doc(hidden) only apply to the original definition, that wouldn't be hard to implement, just a policy decision</p>
</blockquote>
<p>I don't understand the question... are you suggesting we use an old-style macro and provide it at the crate root? I'd be okay with that, not sure what the libs team thinks of this though</p>



<a name="220926622"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220926622" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220926622">(Dec 25 2020 at 16:04)</a>:</h4>
<p><span class="user-mention silent" data-user-id="120791">RalfJ</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220925154">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220875024">said</a>:</p>
<blockquote>
<p><span class="user-mention silent" data-user-id="120791">RalfJ</span> would you be ok with documenting <code>std::raw_const!</code> in the root? If not I can ask about making doc(hidden) only apply to the original definition, that wouldn't be hard to implement, just a policy decision</p>
</blockquote>
<p>I don't understand the question... are you suggesting we use an old-style macro and provide it at the crate root? I'd be okay with that, not sure what the libs team thinks of this though</p>
</blockquote>
<p>yes, that's what I meant</p>



<a name="220926631"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220926631" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220926631">(Dec 25 2020 at 16:05)</a>:</h4>
<p>I don't think the rustdoc bug will be fixed any time soon</p>



<a name="220926643"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220926643" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220926643">(Dec 25 2020 at 16:05)</a>:</h4>
<p>oh wait hold on no - I meant having it available at <em>both</em> <code>std::raw_const!</code> and <code>std::ptr::raw_const!</code></p>



<a name="220926647"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220926647" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220926647">(Dec 25 2020 at 16:05)</a>:</h4>
<p>hmm actually if I make the original in a private module I wonder if that will work <span aria-label="thinking" class="emoji emoji-1f914" role="img" title="thinking">:thinking:</span></p>



<a name="220926765"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220926765" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220926765">(Dec 25 2020 at 16:09)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220926647">said</a>:</p>
<blockquote>
<p>hmm actually if I make the original in a private module I wonder if that will work <span aria-label="thinking" class="emoji emoji-1f914" role="img" title="thinking">:thinking:</span></p>
</blockquote>
<p>it did not :(</p>



<a name="220958618"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220958618" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220958618">(Dec 26 2020 at 10:20)</a>:</h4>
<p><code>#[macro_export]</code> is too <em>stronk</em>. It will even work when used inside an anonymous module such as <code>const _: () = { … };</code>  <span aria-label="sweat smile" class="emoji emoji-1f605" role="img" title="sweat smile">:sweat_smile:</span></p>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220884739">said</a>:</p>
<blockquote>
<p>(could someone move this to <a class="stream" data-stream-id="266220" href="/#narrow/stream/266220-rustdoc">#rustdoc</a> ?)</p>
</blockquote>
<p>I opened <a href="#narrow/stream/266220-rustdoc/topic/.60.23.5Bdoc(hidden).5D.60.20and.20.60pub.20use.60">https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/.60.23.5Bdoc(hidden).5D.60.20and.20.60pub.20use.60</a></p>



<a name="220958763"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220958763" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> RalfJ <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220958763">(Dec 26 2020 at 10:26)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220926643">said</a>:</p>
<blockquote>
<p>oh wait hold on no - I meant having it available at <em>both</em> <code>std::raw_const!</code> and <code>std::ptr::raw_const!</code></p>
</blockquote>
<p><code>std::raw_const!</code> doesn't work as a name, there has to be <code>ptr</code> in there <em>somewhere</em>. But also, if we make this an "old-style macro", I din't think there is precedent for <em>additionally</em> exporting it inside a module?</p>



<a name="220958771"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting%20ptr%3A%3Araw_const/near/220958771" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> RalfJ <a href="https://rust-lang.github.io/zulip_archive/stream/136281-t-lang/wg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const.html#220958771">(Dec 26 2020 at 10:27)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232545">Joshua Nelson</span> <a href="#narrow/stream/136281-t-lang.2Fwg-unsafe-code-guidelines/topic/Documenting.20ptr.3A.3Araw_const/near/220926631">said</a>:</p>
<blockquote>
<p>I don't think the rustdoc bug will be fixed any time soon</p>
</blockquote>
<p><span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> sounded like their hack could probably be made to work Good Enough (TM) to at least start using macros 2.0 in the stdlib?</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>